docs/LED pin PWM.md

   1 # LED pin PWM
   2
   3 Normally LED pin is used to drive WS2812 led strip. LED pin is held low, and every 10ms or 20ms a set of pulses is sent to change color of the 32 LEDs:
   4
   5 ![alt text](/docs/assets/images/ws2811_packets.png  "ws2811 packets")
   6 ![alt text](/docs/assets/images/ws2811_data.png  "ws2811 data")
   7
   8 As alternative function, it is possible to generate PWM signal with specified duty ratio on the LED pin.
   9
  10 Feature can be used to drive external devices. It is also used to simulate [OSD joystick](OSD%20Joystick.md) to control cameras.
  11
  12 PWM frequency is fixed to 24kHz with duty ratio between 0 and 100%:
  13
  14 ![alt text](/docs/assets/images/led_pin_pwm.png  "led pin pwm")
  15
  16 There are four modes of operation:
  17 - low
  18 - high
  19 - shared_low
  20 - shared_high
  21
  22 Mode is configured using ```led_pin_pwm_mode``` setting: ```LOW```, ```HIGH```, ```SHARED_LOW```, ```SHARED_HIGH```
  23
  24 *Note that in any mode, there will be ~2 seconds LOW pulse on boot.*
  25
  26 ## LOW
  27 LED Pin is initialized to output low level by default and can be used to generate PWM signal.
  28
  29 ws2812 strip can not be controlled.
  30
  31 ## HIGH
  32 LED Pin is initialized to output high level by default and can be used to generate PWM signal.
  33
  34 ws2812 strip can not be controlled.
  35
  36 ## SHARED_LOW (default)
  37 LED Pin is used to drive WS2812 strip. Pauses between pulses are low:
  38
  39 ![alt text](/docs/assets/images/ws2811_packets.png  "ws2811 packets")
  40
  41 It is possible to generate PWM signal with duty ratio >0...100%.
  42
  43 While PWM signal is generated, ws2811 strip is not updated.
  44
  45 When PWM generation is disabled, LED pin is used to drive ws2812 strip.
  46
  47 Total ws2812 pulses duration is ~1ms with ~9ms pauses. Thus connected device should ignore PWM signal with duty ratio < ~10%.
  48
  49 ## SHARED_HIGH
  50 LED Pin is used to drive WS2812 strip. Pauses between pulses are high. ws2812 pulses are prefixed with 50us low 'reset' pulse:
  51
  52 ![alt text](/docs/assets/images/ws2811_packets_high.png  "ws2811 packets_high")
  53 ![alt text](/docs/assets/images/ws2811_data_high.png  "ws2811 data_high")
  54
  55  It is possible to generate PWM signal with duty ratio 0...<100%.
  56
  57  While PWM signal is generated, ws2811 strip is not updated.
  58
  59  When PWM generation is disabled, LED pin is used to drive ws2812 strip. Total ws2812 pulses duration is ~1ms with ~9ms pauses. Thus connected device should ignore PWM signal with duty ratio > ~90%.
  60
  61  After sending ws2812 protocol pulses for 32 LEDS, we held line high for 9ms, then send 50us low 'reset' pulse. Datasheet for ws2812 protocol does not describe behavior for long high pulse, but in practice it works the same as 'reset' pulse. To be safe, we also send correct low 'reset' pulse before starting next LEDs update sequence.
  62
  63  This mode is used to simulate OSD joystick. It is Ok that effectively voltage level is held >90% while driving LEDs, because OSD joystick keypress voltages are below 90%.
  64
  65  See [OSD Joystick](OSD%20Joystick.md) for more information.
  66
  67 # Generating PWM signal with programming framework
  68
  69 See "LED Pin PWM" operation in [Programming Framework](Programming%20Framework.md)
  70
  71
  72 # Generating PWM signal from CLI
  73
  74 ```ledpinpwm <value>``` - value = 0...100 -  enable PWM generation with specified duty cycle
  75
  76 ```ledpinpwm``` - disable PWM generation ( disable to allow ws2812 LEDs updates in shared modes )
  77
  78
  79 # Example of driving LED
  80
  81 It is possible to drive single color LED with brightness control. Current consumption should not be greater then 1-2ma, thus LED can be used for indication only.
  82
  83 ![alt text](/docs/assets/images/ledpinpwmled.png  "led pin pwm led")
  84
  85 # Example of driving powerfull white LED
  86
  87 To drive power LED with brightness control, Mosfet should be used:
  88
  89 ![alt text](/docs/assets/images/ledpinpwmpowerled.png  "led pin pwm power_led")
  90